Internationalization/Technical
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. Message MediaWiki uses messages to manage displaying textual elements of the interface. Each message is a key-value pair, with the key identifying the message, and the value holding its contents. Messages SHOULD be self-contained and represent a single logical part of the UI. You MUST use messages for each textual element of the interface. Text MUST NOT be hardcoded. Setup In order to use messages in your extension you need to add the extension's message file to the $wgExtensionMessagesFiles array (this is a global variable), like so: $wgExtensionMessagesFiles'EditAccount' = $dir . 'SpecialEditAccount.i18n.php'; This SHOULD be done in your extension's setup file. Further reading: * add message to skin (Oasis) * core MediaWiki messages Defining a message To add a new message to an extension, you simply need to add a new key-value pair to your .i18n.php file: $messages'en' = array( 'editaccount' => 'Edit account', 'editaccount-desc' => 'Enables staff members to manage user account information', 'editaccount-title' => 'Special:EditAccount', 'editaccount-frame-manage' => 'Edit an account', ); You only need to add a new key for EN (English), versions in other languages will be added as they become available. Note that messages MUST be documented unless they are entirely self-explanatory (this means self-explanatory to a non-native English speaker who has never seen the feature, and might not have ever seen Wikia). Using a message in code Once you've setup your i18n file and defined a message (as detailed above) you can use messages in PHP by calling the wfMsg() function, e.g.: echo wfMsg( 'message-key' ); // echoes content of message This function returns a string with the message contents for the current user's language. If the message you asked for is defined but not available in the current language, it will automatically use a fallback language (usually English). If the message is not defined, it will return: Further reading: * link to other wfMsg functions * link to using messages in JS Language User language vs content language MediaWiki uses two languages on each page: user language and content language. The user language is the language the user has set in their preferences. The user's interface and e-mails sent to the user MUST use this language. By default (for non-logged in users or newly created accounts) this is set to the content language. The content language is the language of the wiki, the language its articles and pages are written in. Things like in-content elements (e.g. Related Pages) and automated comments/edit summaries MUST be rendered in this language. As a rule of thumb, if a message will be generated per-user, it should be in the user language, while if it's to be recorded (usually in the database) and displayed in the same form to all users of a wiki, it should be in the content language. Further reading: * Language in MediaWiki The Language object The Language object is a container for many language- and translation-related convenience methods. You can access the two main instances of Language the object via two global variables: $wgLang (for the user language) and $wgContLang (for the content language). Further reading: * Object definition in SVN: languages/Language.php Using messages in content language As explained above, you can display a message's contents by using wfMsg(). However, that function always uses user language. If you need to display a message in content language, use wfMsgForContent() instead. Context Context is very important when dealing with messages. That is to say: the surrounding interface elements, text and usage flow are all important to the message's content and form. For this reason, you SHOULD NOT re-use a message simply based on the fact that the English version of the text appears in two or more places. Only if both the context and the form of the message in English are the same in both cases, you can re-use a message. What needs to be translated and localized Time and date Time and date may be represented in a number of different ways, depending on the language. Is 9/12/2012 the 9th of December or September 12? Therefore, you MUST''' use relevant methods of the $wgLang and $wgContLang objects', and not hardcode date output formats with PHP's date(). Most commonly used methods: *$wgLang->date() *$wgLang->time() *$wgLang->timeanddate() Numbers While in English the output 1,000 is correct, in Germany it will be 1.000, in Switzerland it will be 1'000 and so on. For this reason you MUST '''use MediaWiki's $wgLang->formatNum( $i ) or $wgContLang->formatNum( $i )' instead of hardcoding decimal points in code. Plural In English, plural forms are always regular, right? One cat, two cats. One sheep, two... sheeps? In many other languages this is more complicated, which is why we need to be careful when using numerical values in or in relation to messages. You MUST use the magic word to alter the message based on different values of the number variable. 'undelete_short' => 'Undelete ', In order for MediaWiki to parse the message correctly, you need to use wfMsgExt() with the parsemag (parse magic words) parameter, like so: wfMsgExt( 'undelete_short', array( 'parsemag' ), $edits ); // $edits is an int Gender Many languages use different forms for people of different gender. Anytime you refer to a user in a message, YOU SHOULD pass the user name as parameter to the message and add a mention in the message documentation that gender is supported. # EN 'blocklog-showlog' => 'This user has been blocked previously.' # PL 'blocklog-showlog' => ' .' In order for MediaWiki to parse the message correctly, you need to use wfMsgExt() with the parsemag (parse magic words) parameter, like so: wfMsgExt( 'blocklog-showlog', array( 'parsemag' ), $username ); // $username is a string Symbols & punctuation Symbols and punctuation need to be translated too! For example, Spanish uses a double question mark, like so: ¿Estás loco? (English: "Are you crazy?"). Similarly, languages other than English use different quotation marks, a different ellipsis, and even a different period (Japanese). For these reasons symbols and punctuation MUST always be part of the message. Namespaces and special pages Namespaces and special page names should also be translatable. This is described in detail in the advanced section. Using parameters Some messages take parameters. They are represented by $1, $2, $3, … in the (static) message texts, and replaced at run time. Typical parameter values are numbers ("Delete 3 versions?"), or user names ("Page last edited by $1"), page names, links, and so on, or sometimes other messages. The most basic usage would look something like this: # message definition in .i18n.php 'myextension-user-page' => "$1's user page", # usage in rendering wfMsg( 'myextension-user-page', $user->getName() ); // outputs: TOR's user page Read next * Advanced technical information * Best practices * Documentation